QuickTime 3 Reference

Previous | Chapter Top | Chapter Contents | Next

Setting Drawing Parameters

The functions described in this section allow you to specify various parameters for drawing operations, such as clipping, scaling, graphics mode, anddecompression quality. All of these functions are based on corresponding routines in the Image Compression Manager for working with image decompression sequences.

GraphicsImportSetBoundsRect

Defines the rectangle in which to draw an image.

extern pascal ComponentResult GraphicsImportSetBoundsRect (
                     GraphicsImportComponent ci,
                     const Rect *bounds);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
bounds
A pointer to a rectangle structure describing the bounding rectangle into which the image will be drawn.

DISCUSSION

You use this function to define the rectangle into which the graphics image should be drawn. The function creates a transformation matrix to map the image's natural bounds to the specified bounds and then calls the GraphicsImportSetMatrix function.

Because this function affects the transformation matrix, you should use the GraphicsImportSetMatrix function GraphicsImportSetMatrix instead of this function when you also need to specify more complex transformation of the matrix.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportGetBoundsRect

Returns the bounding rectangle for drawing.

extern pascal ComponentResult GraphicsImportGetBoundsRect (
                     GraphicsImportComponent ci,
                     Rect *bounds);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
bounds
A pointer to a rectangle structure describing the bounding rectangle that has been defined for the image.

DISCUSSION

This is a convenience function that is implemented by calling GraphicsImportGetMatrix GraphicsImportGetMatrix and GraphicsImportGetNaturalBounds GraphicsImportGetNaturalBounds and using the results to calculate the drawing rectangle.

RESULT Codes

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportSetMatrix

Defines the transformation matrix to use for drawing an image.

extern pascal ComponentResult GraphicsImportSetMatrix (
                     GraphicsImportComponent ci,
                     const MatrixRecord *matrix);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
matrix
A pointer to a matrix structure that specifies how to transform the image during decompression. For example, you can use a transformation matrix to scale or rotate the image. To set the matrix to identity, pass nil in this parameter.

DISCUSSION

The GraphicsImportSetMatrix function establishes the transformation matrix to be applied to an image, which determines where and how it will be drawn.

This function affects the bounding rectangle defined for the image. You can specify where an image will be drawn by setting either a transformation matrix or a bounding rectangle, but it is usually more convenient for applications to set a bounding rectangle using the GraphicsImportSetBoundsRect GraphicsImportSetBoundsRect function.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

SEE ALSO

For more information about transformation matrices and the functions for working with them, see the Movie Toolbox chapter of Inside Macintosh: QuickTime .

GraphicsImportGetMatrix

Returns the transformation matrix to be used for drawing.

extern pascal ComponentResult GraphicsImportGetMatrix (
                     GraphicsImportComponent ci,
                     MatrixRecord *matrix);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
matrix
A pointer to the transformation matrix that has been defined for the image.

DISCUSSION

The transformation matrix is initialized to the identity matrix when the graphics import component is instantiated.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportSetClip

Defines the clipping region for drawing.

extern pascal ComponentResult GraphicsImportSetClip (
                     GraphicsImportComponent ci,
                     RgnHandle clipRgn);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
clipRgn
A handle to a clipping region in the destination coordinate system. Set to nil to disable clipping. The graphics import component makes a copy of this region.

DISCUSSION

Because all drawing operations ignore the port clip, you must use this function to clip an image. The graphics importer component draws only that portion of the image that lies within the specified clipping region.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportGetClip

Returns the current clipping region.

extern pascal ComponentResult GraphicsImportGetClip (
                     GraphicsImportComponent ci,
                     RgnHandle *clipRgn);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
clipRgn
A handle to the clipping region that has been defined for the image. Returns nil if there is no clipping region.

DISCUSSION

The caller must dispose of the returned region handle.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportSetGraphicsMode

Sets the graphics transfer mode for an image.

extern pascal ComponentResult GraphicsImportSetGraphicsMode (
                     GraphicsImportComponent ci,
                     long graphicsMode,
                     const RGBColor *opColor);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
graphicsMode
Specifies the graphics transfer mode to use for drawing the image. QuickTime supports the same graphics modes as Color QuickDraw's CopyBits function (described in Inside Macintosh: Imaging with QuickDraw ) as well as any mode defined by the Image Compression manager, such as alpha modes.
opColor
A pointer to an RGB color structure describing the color to use for blending and transparent operations.

DISCUSSION

You can use this function to specify the graphics transfer mode and color to use for blending and transparent operations.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportGetGraphicsMode

Returns the graphics transfer mode for an image.

extern pascal ComponentResult GraphicsImportGetGraphicsMode (
                     GraphicsImportComponent ci,
                     long *graphicsMode,
                     RGBColor *opColor);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
graphicsMode
A pointer to a long integer. The function returns the QuickDraw graphics transfer mode setting for the image.
opColor
A pointer to an RGB color structure. The function returns the color currently specified for blend and transparent operations.

DISCUSSION

Couldn't read comment.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportSetQuality

Sets the image quality value.

extern pascal ComponentResult GraphicsImportSetQuality (
                     GraphicsImportComponent ci,
                     CodecQ quality);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
quality
Specifies the desired image quality for decompression. Values for this parameter are on the same scale as compression quality. See page 3-57 of Inside Macintosh: QuickTime for a description of the defined quality constants.

DISCUSSION

The quality parameter controls how precisely the decompressor decompresses the image data. Some decompressors may choose to ignore some image data to improve decompression speed.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportGetQuality

Returns the image quality value.

extern pascal ComponentResult GraphicsImportGetQuality (
                     GraphicsImportComponent ci,
                     CodecQ *quality);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
quality
A pointer to the currently specified quality value.

DISCUSSION

The quality value indicates how precisely the decompressor will decompress the image data. Some decompressors may choose to ignore some image data to improve decompression speed.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportSetSourceRect

Sets the source rectangle to use for an image.

extern pascal ComponentResult GraphicsImportSetSourceRect (
                     GraphicsImportComponent ci,
                     const Rect *sourceRect);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
sourceRect
A pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the source image. Set to nil to use the entire image.

DISCUSSION

This function provides a way to use only a portion of the source image. Set the sourceRect parameter to nil to specify that the entire image source rectangle should be used.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available

GraphicsImportGetSourceRect

Returns the current source rectangle for an image.

extern pascal ComponentResult GraphicsImportGetSourceRect (
                     GraphicsImportComponent ci,
                     Rect *sourceRect);
ci
Specifies the component instance that identifies your connection to the graphics importer component.
sourceRect
A pointer to a rectangle structure. The function returns the source rectangle currently specified for the image.

DISCUSSION

This function returns the current source rectangle, as specified by the GraphicsImportSetSourceRect function. The default source rectangle is the image's natural bounds.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified
memFullErr

-108

Not enough memory available
© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next